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The  Hydrologic  Modeling  System  (HEC-HMS):  Design  and  Development  Issues 
William  Charley,  Art  Pabst  and  John  Peters* 


Abstract 


The  Hydrologic  Engineering  Center's  Hydrologic  Modeling  System  (HEC-HMS)  is 
a  software  package  for  precipitation-runoff  simulation.  Software  development  and  architec¬ 
ture  issues  associated  with  development  of  HEC-HMS  are  described.  The  software's  object- 
oriented  structure  and  the  role  of  its  graphical  user  interface  are  presented. 

Introduction 

The  Hydrologic  Engineering  Center  (HEC)  of  the  US  Army  Corps  of  Engineers 
develops  software  for  application  in  the  disciplines  of  hydrologic  and  hydraulic  engineering, 
and  water  resource  planning.  A  project  named  NexGen  is  underway  to  develop  "next- 
generation"  software  to  replace  current,  widely-used  software  such  as  HEC-1  (for 
precipitation-runoff  simulation)  and  HEC-2  (for  steady-flow  water  surface  profide  computa¬ 
tions). 


The  HEC-HMS,  which  will  replace  HEC-1,  is  intended  for  precipitation-runoff 
simulation  using  observed  or  hypothetical  (design)  precipitation.  The  user  can  select  from  a 
variety  of  technical  options  for  each  of  the  major  computational  elements:  precipitation 
specification,  loss  estimation,  excess-to-runoff  transformation,  and  hydrologic  routing.  The 
program  can  be  used  to  simulate  runoff  from  complex  subdivided  watersheds,  and  can 
utilize  distributed  rainfall,  which  is  now  available  from  a  new  generation  of  weather  radars. 
A  basin  "schematic"  capability  enables  the  user  to  configure  the  hydrologic  elements  of  a 
watershed  (such  as  subbasins,  routing  reaches,  reservoirs,  diversions)  graphically,  and  to 
access  editors  and  simulation  results  from  schematic  components.  Requirements  for  the 
HEC-HMS  include  the  following: 
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0  state-of-the-art  engineering  algorithms 

0  comprehensive  Graphical  User  Interface  (GUI) 

0  substantial  use  of  graphics 

0  operational  in  native  X-window  and  Microsoft  Windows  environments 
0  substantial  use  and  manipulation  of  time  series  data 
0  inter-program  data  exchange 

0  an  interface  to  Geographic  Information  Systems 

0  use  of  existing  computational  algorithms  written  in  FORTRAN 
0  extensible  and  easy  to  maintain 

0  distribution  of  the  software  unrestricted,  with  no  run-time  license  fees 
Languages.  Toolkits  and  Libraries 

Historically,  HEC  software  was  developed  in  FORTRAN,  primarily  by  engineers. 
Development  environments  followed  the  typical  progression  of  mainframe  to  mini-computer 
to  personal  computer  and  workstations.  In  preparation  for  NexGen  software  development, 
the  "world"  of  windowing  environments,  event  programming,  GUI's,  the  C  language,  and 
finally,  object  oriented  programming  with  C  -1-  -f  were  explored.  Prototype  applications  were 
developed.  Initial  skepticism  with  object-oriented  programming  turned  into  significant 
support  for  this  technology;  HEC-HMS  is  being  developed  with  object  oriented  techniques. 

To  facilitate  GUI  development  and  porting  to  the  requisite  platforms,  a  commercial 
multi-platform  toolkit  was  acquired.  Although  adoption  of  such  a  toolkit  adds  significantly  to 
an  already  steep  learning  curve,  the  effort  to  develop  and  maintain  separate  platform-specific 
versions  of  source  code  is  avoided.  Some  graphics  are  being  developed  with  relatively  low- 
level  calls  to  routines  in  the  multi-platform  toolkit.  A  commercial  graphics  library  was 
acquired  to  facilitate  development  of  tune  series  graphics.  Versions  of  the  graphics  library 
are  available  for  the  various  target  platforms. 

A  specialized  management  system  designed  for  efficient  handling  of  time  series  data 
has  been  under  progressive  development  since  1979.  The  Data  Storage  System  (HEC-DSS) 
makes  use  of  a  library  of  routines  that  have  capability  to  read  and  write  variable-length, 
named  records  in  a  direct  access  file.  Storage  and  retrieval  of  time  series  data  is  accom¬ 
plished  with  blocks  of  data  of  pre-specified  size  based  on  the  interval  of  the  data.  To 
facilitate  use  of  HEC-DSS  in  object-oriented  applications,  a  set  of  time  series  manager 
classes  were  developed  that  utilize  the  HEC-DSS  library. 

Existing  HEC  software  contain  a  base  of  well  documented  and  tested  FORTRAN 
algorithms  for  performing  hydrologic  computations.  The  algorithms  will  be  useful  in  the 
new  software  and  have  been  incorporated  into  a  library  labeled  libHydro.  Thus,  develop¬ 
ment  of  HEC-HMS  draws  on  mixed  languages  (C-l-  -1-,  C  and  FORTRAN),  and  utilizes  a 
variety  of  libraries. 
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HEC-HMS  Architecture 


Figure  1  illustrates  the  internal  architecture  of  HEC-HMS.  Although  linked  into  a 
single  executable,  there  is  a  clear  separation  between  the  GUI  and  the  simulation  engine, 
where  all  computations  are  managed  and  performed.  This  permits  independent  development 
of  the  GUI  and  the  engine,  and  facilitates  the  utilization  of  an  alternative  GUI  in  the  future, 
should  this  become  desirable.  The  GUI  has  access  to  objects  within  the  engine  through 
public  interfaces.  There  are  no  references  to  the  GUI  from  the  engine,  except  for  calls  to  a 
generic  error  message  dialog  box.  The  user  interacts  with  the  GUI  through  the  windowing 
system,  whether  that  is  on  an  X  device  connected  to  a  UNIX  workstation,  or  Microsoft 
Windows  on  a  PC. 


Figure  1  Software  Architecture 


For  similar  reasons,  clear  separations  are  maintained  between  the  simulation  engine 
and  the  graphics  module,  and  the  engine  and  the  database  interface  module.  The  engine  uses 
objects  that  interface  to  the  database,  and  objects  that  perform  graphics,  but  these  objects 
could  easily  be  modified  to  access  a  different  database  system  or  graphics  package. 

Currently,  time  series  and  similar  data  are  stored  using  HEC-DSS,  while  persistent 
object  data,  such  as  parameters  and  coefficients,  are  stored  in  ASCII  text  files.  The  HEC- 
DSS  provides  a  convenient  and  efficient  way  of  entering,  storing,  retrieving  and  displaying 
series  type  data.  ASCII  text  files  provide  a  convenient  means  for  testing  the  simulation 
engine  independent  of  the  GUI.  It  is  anticipated  that  the  text  files  may  be  replaced  by  a 
database  in  the  future. 

The  engine  is  comprised  of  three  major  components:  the  project  manager,  the 
precipitation  analysis  model,  and  the  basin  runoff  model.  The  project  manager  handles  the 
control  of  the  simulation  time  window,  the  utilization  of  precipitation  and  basin  runoff 
models,  file  names,  and  various  other  management  tasks.  The  precipitation  analysis  model 
computes  subbasin  average  precipitation  from  either  historical  gaged  data  or  from  design 
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storms  that  are  frequency-based  or  that  utilize  Standard  Project  Storm  criteria.  The  basin 
runoff  model  uses  this  precipitation  to  compute  subbasin  discharge  hydrographs,  which  can 
be  routed  through  river  reaches  or  reservoirs,  and  diverted  or  combined  with  other  hydro¬ 
graphs. 


Figure  2  illustrates  use  of  objects  in  HEC-HMS.  The  BasinManager  object  creates, 
manages  and  destroys  the  various  HydrologicElement  objects  that  comprise  the  simulated 
watershed.  When  a  compute  is  requested  by  the  user,  the  BasinManager  finds  the  hydrologic 
object  which  is  acting  as  the  outlet  (all  links,  except  for  diversions,  eventually  point  to  this 
object),  then  sends  it  a  message  to  compute.  Because  the  outlet  object  requires  hydrographs 
from  objects  above  it  for  its  computation,  it  requests  objects  upstream  of  itself  to  compute, 
which  in  turn  request  hydrographs  from  their  upstream  links.  Thus,  the  request  is  propa¬ 
gated  to  all  hydrologic  objects  that  constitute  the  watershed. 


•  •  • 


Figure  2  HEC-HMS  Objects 


Hydrologic  classes  inherit  from  a  fundamental  base  class  titled  HydrologicElement. 
Data  members  of  this  class  contain  information  pertinent  to  all  element  types,  such  as  name, 
description,  type,  etc.  The  classes  Conveyance,  FlowGenerator,  Node,  and  SinkBase  each 
inherit  from  the  HydrologicElement  base  class  to  provide  certain  types  of  connectivity 
functions.  For  example,  the  Conveyance  class  allows  a  link  to  one  upstream  object  (from 
which  to  retrieve  an  inflow  hydrograph),  and  one  downstream  object.  The  FlowGenerator 
class  does  not  allow  links  to  an  upstream  object;  it  can  only  link  to  downstream  objects. 
Member  functions  of  these  classes  provide  a  variety  of  capabilities,  such  as  establishing  and 
deleting  links  to  other  objects,  and  determining  the  cumulative  basin  area.  The  primary 
hydrologic  classes,  which  inherit  firom  these  intermediate  classes,  are  Reach  and  Reservoir 
(from  Conveyance),  Source  and  Subbasin  (from  FlowGenerator),  Diversion  and  Junction 
(from  Node),  and  Sink  (from  SinkBase).  The  data  members  of  a  derived  class  include  data 
associated  with  its  base  class  as  well  as  data  defined  directly  within  the  derived  class. 
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Member  functions  of  these  classes  provide  the  capability  of  setting  and  accessing  data 
parameters,  computing  discharge  hydrographs,  and  performing  other  desired  object  behav¬ 
iors. 


The  primary  hydrologic  objects  generally  use  "process"  objects  to  implement  the 
different  computational  methods.  For  example.  Subbasin  objects  instantiate  objects  from  a 
moisture  accounting  class,  a  runoff  transform  class,  and  a  baseflow  class.  The  object 
instantiated  depends  on  the  hydrologic  method  used.  A  GreenAmpt  object  or  a 
InitialConstant  object  might  be  instantiated  for  moisture  accounting,  depending  on  the 
method  selected  by  the  user.  A  Snyder  object,  or  Clark  object,  or  Kinematic  Wave  object 
might  be  instantiated  for  the  runoff  transform.  A  process  object  has  as  data  members  the 
unique  parameter  data  required  for  the  particular  method,  and  a  member  function  to  compute 
(e.g.,  compute  excess  given  the  precipitation).  In  many  cases  the  "compute"  member 
functions  call  routines  from  libHydro  to  perform  the  actual  computation. 

Each  process  class  inherits  from  a  base  class  for  the  process  group  that  contains 
capabilities  common  to  all  the  method  classes  within  that  group.  For  example,  the  moisture 
accounting  base  class  defines  time  series  objects  to  retrieve  the  subbasin  precipitation  and 
store  the  computed  excess  precipitation  that  are  needed  by  all  derived  classes.  Likewise  the 
runoff  transform  base  class  defines  time  series  objects  that  obtain  the  excess  precipitation  and 
store  the  computed  hydrograph  for  all  types  of  derived  transform  classes. 

The  TimeSeries  class  inherits  from  the  DataManager  class,  which  accesses  the 
HEC-DSS  database  software.  DataManager  contains  several  "static"  member  functions,  one 
of  which  points  to  buffers  of  data  retrieved  and  stored.  When  an  object  retrieves  (or  stores) 
a  set  of  data  that  is  already  in  a  memory  buffer,  no  actual  file  access  is  required. 

As  previously  indicated,  persistent  storage  of  data  parameters  and  coefficients  is 
presently  achieved  with  ASCII  text  files.  As  an  example  of  objects  interacting  and  working 
with  each  other,  when  the  user  requests  to  save  data  parameters  in  persistent  storage,  the 
BasinManager  sends  a  message  to  each  hydrologic  object  to  save  its  own  data.  After  saving 
its  data,  each  hydrologic  object  in  turn  sends  a  message  to  its  processor  objects  to  save  their 
data.  To  re-establish  a  "model"  from  a  persistent  data  file,  a  data  loading  object  recreates 
hydrologic  objects  via  the  BasinManager,  and  sets  their  data  parameters  and  coefficients 
through  their  public  interfaces.  In  this  procedure,  as  far  as  the  engine  is  concerned,  the 
objects  are  created  and  parameters  set  just  as  if  this  action  were  being  done  by  the  user 
through  the  GUI. 

Graphical  User  Interface 

The  GUI  is  the  window  through  which  the  user  interacts  with  HEC-HMS.  It  enables 
specification  of  information  to  be  retrieved  or  stored  (e.g.,  data  files),  specification  of 
application-specific  information  (both  data  and  task  instructions),  and  viewing  of  results. 

The  GUI  enables  the  user  to  easily  and  effectively  perform  the  various  types  of  analysis  for 
which  the  program  is  capable. 

With  the  GUI,  the  user  can  define,  change,  control,  and  view  a  model's  configura¬ 
tion,  inputs  and  results.  The  multiple  windows  shown  in  Figure  3  illustrates  some  of  the 
screens  that  comprise  the  GUI  for  an  example  watershed.  The  screens  are,  in  a 
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Figure  3  Graphical  User  Interface 


counter  clockwise  order  from  the  upper  left:  1)  the  schematic  configuration  of  hydrologic 
elements  that  make  up  the  example  Allegheny  Basin  model;  2)  a  data  editor  for  entering  or 
changing  information  for  a  junction  object;  3)  a  tabular  report  of  critical  flows  for  each 
hydrologic  element;  4)  a  graphic  of  subbasin  precipitation  and  flow  results;  5)  a  perspective 
view  of  a  precipitation  field  over  the  entire  basin;  and  6)  a  graphic  of  the  flows  entering  and 
leaving  a  junction.  Each  of  these  windows  make  up  a  portion  of  the  complete  GUI.  The 
user  may  open  any  number  of  graphical  and  tabular  windows  to  display  reports  and  model 
information  for  any  hydrologic  element  of  interest. 

The  user-controlled  schematic  representation  of  the  components  of  a  hydrologic 
system  is  a  key  element  of  the  GUI.  The  schematic  employs  icons  to  represent  subbasins, 
routing  reaches,  reservoirs,  diversions,  etc.,  and  their  topological  connections.  In  creating  a 
new  watershed  model,  the  user  selects  an  element  type  (e.g.,  subbasin)  from  a  popup  menu 
and  drags  it  to  a  desired  location  on  the  schematic  background.  Other  elements  are  estab¬ 
lished  in  a  similar  fashion,  as  are  connecting  links  between  elements.  An  element  can  then 
be  selected,  and  access  to  a  data  editor  for  that  element  is  provided  as  an  option  from  a 
popup  menu.  After  a  simulation  has  been  executed,  an  element  can  again  be  selected,  and  a 
popup  menu  provides  access  to  a  display  of  simulation  results  for  that  element. 

Navigation  through  the  schematic  is  facilitated  with  a  view  finder  window  that  shows 
a  miniature  view  of  the  entire  schematic,  and  a  frame  around  that  portion  of  the  schematic 
presently  visible.  The  user  can  move  the  frame  to  bring  other  portions  of  the  schematic  into 
view.  Capability  is  also  provided  to  "collapse"  portions  of  the  schematic  so  that  unwanted 
detail  can  be  hidden  from  view. 

The  schematic  capability  is  required  in  a  number  of  NexGen  software  products 
besides  HEC-HMS,  such  as  those  for  simulating  reservoir  systems  and  river  hydraulics,  and 
for  analyzing  flood  damage.  Hence  the  approach  for  developing  the  capability  was  to 
develop  a  Schematic  Model  Library  (SML)  which  consists  of  C  +  +  classes  for  general 
application.  The  SML  links  with  libraries  from  the  multi-platform  toolkit  so  that  the 
schematic  capability  is  portable  across  platforms. 

Where  several  GUI  windows  display  the  same  data  value  or  information  related  to  a 
data  value,  it  is  necessary  to  provide  a  mechanism  to  assure  that  the  contents  of  all  windows 
remain  current.  If,  for  example,  the  drainage  area  in  the  data  edit  window  were  changed, 
then  the  tabular  report,  which  shows  each  element's  area,  would  need  to  be  updated.  All 
model  results  that  are  affected  by  the  drainage  area  value  would  no  longer  be  current.  To 
provide  a  mechanism  to  systematically  handle  the  update  of  windows,  "observer"  objects  are 
used.  An  observer  object  allows  a  window  to  register  its  interest  in  being  notified  when 
specific  model  data  is  changed.  Thus,  the  object  that  generates  the  report  could  use  an 
observer  object  to  notify  a  hydrologic  element  object  of  its  interest  in  knowing  of  a  change  in 
drainage  area.  The  report  object  would  then  be  able  to  update  the  particular  data  value,  or 
regenerate  the  complete  report. 

While  the  user  is  able  to  interact  with  the  model  through  the  GUI  to  accomplish  her 
or  his  modeling  needs,  it  is  frequently  desirable  to  repeat  a  sequence  of  model  interactions 
over  and  over  again  with  different  model  parameters.  Under  this  scenario  the  GUI  as  the 
means  of  carrying  out  repeated  operations  can  become  the  user’s  greatest  frustration.  A 
similar  need  for  an  alternate  to  the  GUI  model  control  capability  occurs  when  a  model  must 
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be  operated  unattended,  or  under  the  control  of  another  higher  level  modeling  process  that 
sees  the  hydrologic  model  as  only  a  contributing  component.  In  each  of  these  cases  the 
ability  to  drive  the  model  from  a  script  of  instructions  which  include  both  control  and  data 
values  is  needed.  In  its  full  implementation  the  model  design  will  permit  the  user  to  define 
any  number  of  macro  scripts  that  can  be  invoked  to  simplify  often  repeated  model  GUI 
sequences.  An  example  might  be  a  tool  bar  allowing  the  selection  of  a  macro  to  trigger  the 
routine  generation  of  six  hardcopy  plots  and  four  reports  to  summarize  model  results. 

The  GUI  design  requires  careful  consideration  of  many  issues  such  as,  the  mental 
image  a  user  will  have  of  the  problem  solving  steps,  logical  navigation  through  those  steps, 
the  organization  of  related  data  into  specific  GUI  screens,  the  aesthetic  layout  of  the 
information  on  each  screen,  look  and  feel  consistent  with  the  parent  windowing  system,  and 
adequate  handling  of  error  conditions. 

Closing  Comment 

The  current  architecture  and  development  plans  for  HEC-HMS  reflect  the  set  of 
requirements  listed  in  the  Introduction  and  experience  to  date  in  model  development.  While 
the  learning  curves  have  been  steep  and  initial  development  has  progressed  much  more 
slowly  than  was  originally  anticipated,  we  find  that  we  are  now  able  to  extend  existing 
modeling  capabilities  and  continue  model  development  in  a  reasonably  efficient  and  straight 
forward  manner.  We  also  anticipate  that  software  maintenance  will  be  facilitated,  and  that 
future  adoption  of  alternative  graphics,  GUI  or  database  features  will  not  require  a  major 
rewrite  of  the  computational  engine  or  other  components. 
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